home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2001 / MacHack 2001.toast / pc / The Hacks / pseudoDoc / ExampleHeaders / IOCommandGate.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-06-23  |  6.9 KB  |  162 lines
  1. /* Sample C++ Header -- Used for HeaderDoc testing.*/
  2. /*!  @language embedded-c++ */
  3.  
  4. #ifndef _IOKIT_IOCOMMANDGATE_H
  5. #define _IOKIT_IOCOMMANDGATE_H
  6.  
  7. #include <IOKit/IOEventSource.h>
  8.  
  9. /*!
  10.      @class IOCommandGate : public IOEventSource
  11.      @abstract Single-threaded work-loop client request mechanism.
  12.      @discussion An IOCommandGate instance is an extremely light way mechanism
  13. that executes an action on the driver's work-loop.  'On the work-loop' is
  14. actually a lie but the work-loop single threaded semantic is 
  15. maintained for this
  16. event source.  Using the work-loop gate rather than execution by the workloop.
  17. The command gate tests for a potential self dead lock by checking if the
  18. runCommand request is made from the work-loop's thread, it doens't check for a
  19. mutual dead lock though where a pair of work loop's dead lock each other.
  20.  
  21.      The IOCommandGate is a lighter weight version of the IOCommandQueue and
  22. should be used in preference.  Generally use a command queue whenever 
  23. you need a
  24. client to submit a request to a work loop.  A typical command gate action would
  25. check if the hardware is active, if so it will add the request to a pending
  26. queue internal to the device or the device's family.  Otherwise if the hardware
  27. is inactive then this request can be acted upon immediately.
  28.  
  29.      The run functions can not be called from an interrupt context.
  30.  
  31. */
  32. class IOCommandGate : public IOEventSource
  33. {
  34.      OSDeclareDefaultStructors(IOCommandGate)
  35.  
  36. public:
  37. /*!
  38.      @typedef Action
  39.      @discussion Type and arguments of callout C function that is used when
  40. a runCommand is executed by a client.  Cast to this type when you want a C++
  41. member function to be used.  Note the arg1 - arg3 parameters are straight pass
  42. through from the runCommand to the action callout.
  43.      @param owner
  44.          Target of the function, can be used as a refcon.  The owner is set
  45. during initialisation of the IOCommandGate instance.     Note if a C++ function
  46. was specified this parameter is implicitly the first paramter in the target
  47. member function's parameter list.
  48.      @param arg0 Argument to action from run operation.
  49.      @param arg1 Argument to action from run operation.
  50.      @param arg2 Argument to action from run operation.
  51.      @param arg3 Argument to action from run operation.
  52. */
  53.      typedef IOReturn (*Action)(OSObject *owner,
  54.                                 void *arg0, void *arg1,
  55.                                 void *arg2, void *arg3);
  56.  
  57. protected:
  58. /*!
  59.      @function checkForWork
  60.      @abstract Not used.
  61.      @discussion This function is a pure virtual function in IOEventSource and
  62. thus MUST be implemented in IOCommandGate, but the command gate short circuits
  63. the traditional IOEventSource/IOWorkLoop relationship.
  64.      @param moreP
  65.     Return boolean used to inform the workloop that this event source has
  66. more work to be processed later.
  67.      @param wakeupTimeP
  68.     Return parameter to indicate a timeout when this IOEventSource must
  69. be checked again, the time is currently absolute.
  70. */
  71.      virtual void checkForWork(bool *moreP, mach_timespec_t *wakeupTimeP);
  72.  
  73. /*!
  74.      @function inlineFunctionOneLine
  75.      @abstract Test of the handling of inline functions.
  76.      @discussion This function is inlined and defined all on one line.
  77. */
  78.     void inlineFunctionOneLine() { return foo; };
  79.  
  80. /*!
  81.      @function inlineFunctionMultiLine
  82.      @abstract Test of the handling of inline functions.
  83.      @discussion This function is inlined and defined on several lines.
  84. */
  85.     void inlineFunctionMultiLine() { 
  86.         return foo; 
  87.     };
  88.  
  89. public:
  90. /*!
  91.      @function commandGate
  92.      @abstract Static function used as a factory to create new 
  93. IOCommandGate.    See init.
  94.      @param owner
  95.     Owner of this instance of the IOCommandGate.  This argument will be
  96. used as the first parameter in the action callout.
  97.      @param action
  98.     Pointer to a C function that is called whenever a client of the
  99. IOCommandGate calls runCommand.     NB Can be a C++ member function but caller
  100. must cast the member function to IOCommandGateAction and they will get a
  101. compiler warning.  Defaults to zero, see IOEventSource::setAction.
  102. */
  103.      static IOCommandGate *
  104.          commandGate(OSObject *owner, IOCommandGate::Action action = 0);
  105. /*!
  106.      @function init
  107.      @abstract Class initialiser.
  108.      @discussion Initialiser for IOCommandGate operates only on newly 'newed'
  109. objects.  Shouldn't be used to re-init an existing instance.
  110.      @param owner Owner of this instance of the IOCommandGate.
  111.      @param action
  112.     Pointer to a C function that is called whenever a client of the
  113. IOCommandGate calls runCommand.  Defaults to zero, see 
  114. IOEventSource::setAction.
  115.      @result True if inherited classes initialise successfully.
  116. */
  117.      virtual bool init(OSObject *owner, IOCommandGate::Action action = 0);
  118.  
  119. /*!
  120.      @function runCommand
  121.      @abstract Single thread a command with the target work-loop.
  122.      @discussion Client function that causes the current action to be called in
  123. a single threaded manner.  Beware the work-loop's gate is recursive and command
  124. gates can cause direct or indirect re-entrancy.  When the executing on a
  125. client's thread runCommand will sleep until the work-loop's gate opens for
  126. execution of client actions, the action is single threaded against all other
  127. work-loop event sources.
  128.      @param arg0 Parameter for action of command gate, defaults to 0.
  129.      @param arg1 Parameter for action of command gate, defaults to 0.
  130.      @param arg2 Parameter for action of command gate, defaults to 0.
  131.      @param arg3 Parameter for action of command gate, defaults to 0.
  132.      @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
  133. event source is currently disabled, kIOReturnNoResources if no action 
  134. available.
  135. */
  136.      virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
  137.                                  void *arg2 = 0, void *arg3 = 0);
  138.  
  139. /*!
  140.      @function runAction
  141.      @abstract Single thread a call to an action with the target work-loop.
  142.      @discussion Client function that causes the given action to be called in
  143. a single threaded manner.  Beware the work-loop's gate is recursive and command
  144. gates can cause direct or indirect re-entrancy.  When the executing on a
  145. client's thread runCommand will sleep until the work-loop's gate opens for
  146. execution of client actions, the action is single threaded against all other
  147. work-loop event sources.
  148.      @param action Pointer to function to be executed in work-loop context.
  149.      @param arg0 Parameter for action of command gate, defaults to 0.
  150.      @param arg1 Parameter for action of command gate, defaults to 0.
  151.      @param arg2 Parameter for action of command gate, defaults to 0.
  152.      @param arg3 Parameter for action of command gate, defaults to 0.
  153.      @result kIOReturnSuccess if successful. kIOReturnBadArgument if 
  154. action is not defined, kIOReturnNoResources if no action available.
  155. */
  156.      virtual IOReturn runAction(Action action,
  157.                                 void *arg0 = 0, void *arg1 = 0,
  158.                                 void *arg2 = 0, void *arg3 = 0);
  159. };
  160.  
  161. #endif /* !_IOKIT_IOCOMMANDGATE_H */
  162.